Edebug doc fixes

* doc/lispref/edebug.texi (Instrumenting Macro Calls):
Mention defining macros at instrumentation time.
(Edebug Options): Mention edebug-unwrap-results.

* lisp/emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
Comments.

* admin/FOR-RELEASE: Markup.

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 1f498e06c31de06c58427ae67545d6adb7a72f00..ec12b977b9eea62e450d8a82c877fc8392208b5a 100644 (file)
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -183,7 +183,7 @@ xresources.texi   cyd
 abbrevs.texi      rgm
 advice.texi       cyd
 anti.texi         
-back.texi
+back.texi         rgm
 backups.texi      cyd
 buffers.texi      cyd
 commands.texi     cyd
@@ -192,7 +192,7 @@ control.texi      cyd
 customize.texi    cyd
 debugging.texi    cyd
 display.texi      cyd
-edebug.texi
+edebug.texi       rgm
 elisp.texi
 errors.texi       rgm
 eval.texi         cyd

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 50797248423de94aa669c4102253b86e23f8d3ac..4116605ebc7e4c9d47e70a6130651fd11176f4fc 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+       * edebug.texi (Instrumenting Macro Calls):
+       Mention defining macros at instrumentation time.
+       (Edebug Options): Mention edebug-unwrap-results.
+
 2012-03-31  Eli Zaretskii  <eliz@gnu.org>
 
        * text.texi (Special Properties): Clarify the description of the

diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 33e5e54f1c61cc94eba7200a4f8e5748a1b1b8d5..245aaf94c6db6370930c19d1b91a85197b7bbb5c 100644 (file)
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1113,6 +1113,15 @@ definition, but specifications are much more general than macro
 arguments.  @xref{Defining Macros}, for more explanation of
 the @code{declare} form.
 
+@c See eg http://debbugs.gnu.org/10577
+@c FIXME  Maybe there should be an Edebug option to get it to
+@c automatically load the entire source file containing the function
+@c being instrumented.  That would avoid this.
+  Take care to ensure that the specifications are known to Edebug when
+you instrument code.  If you are instrumenting a function from a file
+that uses @code{eval-when-compile} to require another file containing
+macro definitions, you may need to explicitly load that file.
+
   You can also define an edebug specification for a macro separately
 from the macro definition with @code{def-edebug-spec}.  Adding
 @code{debug} declarations is preferred, and more convenient, for macro
@@ -1255,6 +1264,8 @@ Each of the following elements is matched as alternatives as if by using
 of them match, nothing is matched, but the @code{&not} specification
 succeeds.
 
+@c FIXME &key?
+
 @item &define
 @c @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
@@ -1422,7 +1433,15 @@ of the bindings is either a symbol or a sublist with a symbol and
 optional expression.  In the specification below, notice the @code{gate}
 inside of the sublist to prevent backtracking once a sublist is found.
 
-@c FIXME? The actual definition in edebug.el does not have a gate.
+@ignore
+@c FIXME?  The actual definition in edebug.el looks like this (and always
+@c has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
+@c this is just an example for illustration?
+(def-edebug-spec let
+  ((&rest
+    &or (symbolp &optional form) symbolp)
+   body))
+@end ignore
 @example
 (def-edebug-spec let
   ((&rest
@@ -1566,7 +1585,28 @@ debugged.
 @xref{Edebug Execution Modes}.
 @end defopt
 
-@c FIXME edebug-unwrap-results
+@defopt edebug-unwrap-results
+If non-@code{nil}, Edebug tries to remove any of its own
+instrumentation when showing the results of expressions.  This is
+relevant when debugging macros where the results of expressions are
+themselves instrumented expressions.  As a very artificial example,
+suppose that the example function @code{fac} has been instrumented,
+and consider a macro of the form:
+
+@c FIXME find a less silly example.
+@smallexample
+(defmacro test () "Edebug example."
+  (if (symbol-function 'fac)
+      @dots{}))
+@end smallexample
+
+If you instrument the @code{test} macro and step through it, then by
+default the result of the @code{symbol-function} call has numerous
+@code{edebug-after} and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result.  If
+@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
+these forms from the result.
+@end defopt
 
 @defopt edebug-on-error
 Edebug binds @code{debug-on-error} to this value, if

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 94950e330abb6716155f0e2ca95602b83d2f6e8a..24b57954df41fa1a52c554f2848f9d011ad05576 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+       * emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
+
 2012-03-30  Thierry Volpiatto  <thierry.volpiatto@gmail.com>
 
        * dired-aux.el (dired-copy-file-recursive, dired-create-files):

diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index c241ac710cf6697de618491bdf9a29e32803067b..67ffd6d5d31bc3379ea498603a5e1c1cded70de8 100644 (file)
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -1,6 +1,6 @@
 ;;; edebug.el --- a source-level debugger for Emacs Lisp
 
-;; Copyright (C) 1988-1995, 1997, 1999-2012  Free Software Foundation, Inc.
+;; Copyright (C) 1988-1995, 1997, 1999-2012 Free Software Foundation, Inc.
 
 ;; Author: Daniel LaLiberte <liberte@holonexus.org>
 ;; Maintainer: FSF
@@ -191,6 +191,7 @@ Use this with caution since it is not debugged."
 
 (defcustom edebug-unwrap-results nil
   "Non-nil if Edebug should unwrap results of expressions.
+That is, Edebug will try to remove its own instrumentation from the result.
 This is useful when debugging macros where the results of expressions
 are instrumented expressions.  But don't do this when results might be
 circular or an infinite loop will result."
@@ -2028,7 +2029,10 @@ expressions; a `progn' form will be returned enclosing these forms."
 (def-edebug-spec apply (function-form &rest form))
 (def-edebug-spec funcall (function-form &rest form))
 
-;; FIXME? The manual has a gate here.
+;; FIXME?  The manual uses this form (maybe that's just for illustration?):
+;; (def-edebug-spec let
+;;   ((&rest &or symbolp (gate symbolp &optional form))
+;;    body))
 (def-edebug-spec let
   ((&rest &or (symbolp &optional form) symbolp)
    body))
@@ -4157,6 +4161,8 @@ You must include newlines in FMT to break lines, but one newline is appended."
 ;;; Frequency count and coverage
 
 ;; FIXME should this use overlays instead?
+;; Definitely, IMO.  The current business with undo in
+;; edebug-temp-display-freq-count is horrid.
 (defun edebug-display-freq-count ()
   "Display the frequency count data for each line of the current definition.
 The frequency counts are inserted as comment lines after each line,
@@ -4226,6 +4232,8 @@ reinstrument it."
        (insert "\n")
        (setq i first-index)))))
 
+;; FIXME this does not work very well.  Eg if you press an arrow key,
+;; or make a mouse-click, it fails with "Non-character input-event".
 (defun edebug-temp-display-freq-count ()
   "Temporarily display the frequency count data for the current definition.
 It is removed when you hit any char."
@@ -4235,6 +4243,7 @@ It is removed when you hit any char."
     (undo-boundary)
     (edebug-display-freq-count)
     (setq unread-command-char (read-char))
+    ;; Yuck!  This doesn't seem to work at all for me.
     (undo)))
 
 \f